Ion Developer Information
See ion.txt for information on Ion.
See libs.txt for information on Ion libraries.

+---------------------------------------------------------------+
| Background							|
+---------------------------------------------------------------+
Assembling Ion programs requires that you have TASM and Devpac83.
You can get these programs at ticalc.org, calc.org and some other
TI-calculator web sites.
Instead of using the zasm batch file that comes with Devpac83,
use the asm batch file that comes with Ion. This program will
assemble your code for both the TI-83 and the TI-83 Plus in one
step (type 'asm progname' at a DOS prompt).

+---------------------------------------------------------------+
| File Formats							|
+---------------------------------------------------------------+
>Programs
All Ion programs must follow the Ion program format in order for
Ion to display them. The format is as follows:
	.nolist			;\
	#include "ion.inc"	; \
	.list			;  \
#ifdef TI83P			;   \
	.org	progstart-2	;    > Ion Program Header
	.db	$BB,$6D		;   /
#else				;  /
	.org	progstart	; /
#endif				;/
	ret		; use xor a if libraries are not used
	jr	nc,start	; jump to the beginning
	.db	"This is the description",0
start:	; Program code goes here
	ret
.end
; End of Program

>Modules
Modules are programs that run at Ion startup, shutdown, and when
an undefined key is pressed in Ion. The format of an Ion module
is as follows:
	.nolist			;\
	#include "ion.inc"	; \
	.list			;  \
#ifdef TI83P			;   \
	.org	sram-2		;    > Ion Module Header
	.db	$BB,$6D		;   /
#else				;  /
	.org	sram		; /
#endif				;/
	ret		; modules must not run from the TI-OS
	.db	1	; identify program type as a module
start:	; Module code goes here
	ld	a,1	; normal return
	ret		; return when finished
.end
; End of Module
Ion passes values to modules before running them. These values are:
-a holds the keycode (_getk style). It contains 255 on Ion
 startup and 55 on Ion shutdown.
-op1 holds the name of the highlighted program. Use _chksysvar to
 get program information.
-You may use only saferam2 (statram) and the remaining bytes of
 sram in you module.
-If your module modifies code past $BFFF make sure to do a di.
-On return Ion expects a value in register a to determine whether
 or not to restart. If a equals zero on return, Ion will restart
 immediately. Otherwise Ion will continue normally. Storing zero
 to register a is not recommended, although possible, at startup
 or shutdown.
-You CANNOT use library routines from within modules.
-Modules CANNOT exceed 768 bytes!

>Libraries
Ion has eight built in library functions. To use these functions,
simply call them (they are defined in ion.inc). See libs.txt for
information on using these functions.
If you use libraries, your program may not exceed 7000 bytes
(normally there is a 8196 limit on the TI-83 Plus).
If you must exceed 7000 bytes, make sure you disable interrupts
before going past that limit!

+---------------------------------------------------------------+
| Misc Programming Info						|
+---------------------------------------------------------------+
>Memory Areas
On the TI-83 you may use any memory area for your program except
the command shadow (except for modules; see the section on
modules for more information). On the TI-83 Plus you may only use
those areas of RAM that are also allowed on the TI-83 unless you
want to make your program to not be compatable with the TI-83. To 
make things easier, ion.inc includes some safe RAM areas with
easy names. They are:
	-saferam1 (768 bytes, APD buffer)
	-saferam2 (512 bytes, statram)
	-saferam3 (128 bytes, text memory).

+---------------------------------------------------------------+
| Standards							|
+---------------------------------------------------------------+
>Naming Schemes
All modules should have the prefix "ZM" at the beginning of the
program name. Regular programs should be named something as
similar as possible to their real name or function.

>Compatability Issues (TI83 vs. TI83P)
The TI-83 Plus has more safe memory areas than the TI-83. It is
recommended that these memory areas not be used unless you plan
to do something different on each calculator or you do not intend
on making a TI-83 version of your program. Unless your program is
intended as a Flash utility or other utility that will only work
on one calculator, it is highly recommended that you make it
assemble for either platform. Ion was designed with compatability
in mind for both calculators. Use the asm batch file (included
with Ion) to assemble your programs.
The TI-83 Plus cannot run programs larger than 8192 bytes. Try to
keep all programs under this limit. If you must go past 8192
bytes, you can by putting only those routines that do not use ROM
calls at the end of your program and executing a di before
calling those functions.
All TI-83 specific code should be between an '#ifdef TI83' and
an '#endif'. All TI-83 Plus specific code should be between an
'#ifdef TI83P' and an '#ifdef TI83'. Even if your program will
not assemble for one of the calculators, the '#ifdef' blocks are
required for assembly.

>Include Files
Ion is packaged with an include file (ion.inc). It is recommended
that you use this file instead of ti83asm.inc, joeti83p.inc, or
another include file. The Ion include file allows programs to be
easily ported between the TI-83 and the TI-83 Plus. The naming
scheme used in this include file is closely related to TI's
naming scheme. See the examples given above for using this
include file.

>Releasing Programs
When you release a program, I recommend assembling the program
for both the TI-83 and the TI-83 Plus even if you do not own both
calculators. In most cases this will require no extra work (if
you use the asm batch file included with Ion). Of course, if your
program directly accesses the VAT or another resource that is
different, more changes will be necessary (use #ifdef where
necessary). When you release the program, the program should be
named *.83p for the TI-83 version and *.8xp for the TI-83 Plus
version. This is done automatically by asm. If bugs are found in
ion.inc, please let me know so I can resolve them.
I recommend releasing all programs with a file with the same
name as your program but with a txt extension for your
documentation.

>Grouping Programs
The asm batch file that comes with Ion does not assemble the
TI-83 Plus version of programs with the correct TI-83 Plus
header. Because of this you must group your programs as TI-83
programs and not TI-83 Plus programs. To do this select Group
TI-83 Programs and then type *.8* instead of *.83p which appears
automatically in the program name box. After grouping name the
file *.8xp for the TI-83 Plus version.

Joe Wingbermuehle
http://joewing.calc.org
